docs(adr): add ADR 0066 for interactive admin install guide by ifireball · Pull Request #3020 · fullsend-ai/fullsend

ifireball · 2026-07-05T10:51:29Z

Summary

Add ADR 0066: revive admin install as an interactive guided orchestrator, not a monolithic provisioner.
The command walks a versioned install decision tree (YAML) and delegates to existing mint / github / inference / repos phases.
Same tree drives a future agent install-guidance skill; --plan emits composed commands without executing.
Update docs/architecture.md with the decided interactive install entry point.

Context

Standalone install commands reduced coupling but increased cognitive load. Recent docs deprecated all-in-one admin install as opaque; this ADR reframes it as the guided entry point while keeping per-repo as the default path (ADR 0044).

Test plan

make lint passes (ADR frontmatter, numbers, link scope)
Review ADR Decision aligns with existing standalone command split (feat(cli): add github sub-command for standalone org/repo setup #1259, feat(cli): add mint sub-command for standalone GCP mint management #1261, docs: deprecate all-in-one admin, restructure reference/ into sidebar sections #2698)
Confirm ADR 0066 number does not collide with in-flight ADRs (docs(adr): add ADR 0068 for ready-made configuration presets #2743, docs(adr): add ADR 0065 for human-gated permission adjustments #2830)

Made with Cursor

Record the decision to revive admin install as a guided orchestrator over existing mint/github/inference/repos phases, with a shared decision tree for humans and agent skills. Signed-off-by: Barak Korren <bkorren@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>

fullsend-ai-review · 2026-07-05T10:52:15Z

🤖 Review · ⚠️ Cancelled · Started 10:52 AM UTC · Ended 11:03 AM UTC
Commit: 0a95cac · View workflow run →

qodo-code-review · 2026-07-05T10:52:21Z

PR Summary by Qodo

Add ADR 0066: guided interactive admin install orchestrator

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add ADR 0066 documenting admin install as an interactive installation orchestrator.
• Define a versioned YAML decision tree driving both CLI guidance and future agent skills.
• Update architecture docs to reference the new guided install entry point.

Diagram

graph TD
  H(["Human operator"]) --> CLI["`admin install` (CLI)"] --> PH["Phase commands (mint/github/inference/repos)"] --> EXT{{"GitHub/GCP/Infra"}}
  A(["Agent" ]) --> SK["Install-guidance skill"] --> TREE[["Decision tree (YAML)" ]] --> CLI

  subgraph Legend
    direction LR
    _actor(["Actor" ]) ~~~ _svc["Command/service" ] ~~~ _art[["Versioned artifact" ]] ~~~ _ext{{"External"}}
  end

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep standalone commands only (docs-only guidance)

➕ No interactive orchestration to maintain
➕ Lowest CLI surface area and fewer implicit behaviors
➖ High cognitive load and higher onboarding error rate
➖ Hard for agents to give bounded, consistent guidance without a shared decision model

2. New top-level command (e.g., `fullsend install`)

➕ Clean slate; avoids legacy expectations tied to admin install
➕ Can be designed purely around guided orchestration semantics
➖ Adds another entry point and more docs to maintain
➖ Loses familiarity of the established admin install mental model

3. Web/UI installer consuming a normative spec

➕ Potentially best UX and easiest branching visualization
➕ Naturally shareable for both humans and automation
➖ Higher upfront scope and delivery risk
➖ Requires a stricter contract (normative spec) and compatibility guarantees earlier

Recommendation: The ADR’s chosen approach—reviving admin install as an interactive orchestrator backed by a versioned YAML decision tree—is a good middle ground: it reduces adopter/agent cognitive load while keeping the existing standalone commands as the stable execution layer. Deferring a normative spec until there’s a second consumer is reasonable, as long as the YAML schema is documented and tested alongside the artifact.

Files changed (2) +109 / -0

Documentation (2) +109 / -0

0066-interactive-admin-install-guide.mdAdd ADR 0066 defining guided interactive 'admin install' +108/-0

Add ADR 0066 defining guided interactive 'admin install'

• Introduces a new accepted ADR describing 'admin install' as an interactive, TTY-driven orchestrator that delegates to existing 'mint'/'github'/'inference'/'repos' phases. Specifies a versioned YAML decision tree shared by the CLI and future agent install-guidance skills, including '--guided' and '--plan' behaviors and coverage expectations.

docs/ADRs/0066-interactive-admin-install-guide.md

architecture.mdDocument 'admin install' as the interactive install entry point +1/-0

Document 'admin install' as the interactive install entry point
• Adds an architecture bullet linking to ADR 0066 and positioning 'admin install' as the guided orchestrator over existing installation phases rather than a monolithic provisioner.
docs/architecture.md

github-actions · 2026-07-05T10:53:33Z

Site preview

Preview: https://46b83fee-site.fullsend-ai.workers.dev

Commit: 59b0509f70d9e03608e6e76a4192375b8d190150

qodo-code-review · 2026-07-05T10:54:08Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. ~~Admin install docs conflict~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/architecture.md now presents admin install as the guided install entry point, but other docs
still label fullsend admin install as deprecated and recommend avoiding it, which will confuse
readers about the recommended workflow. This should be reconciled to reflect ADR 0066’s nuance
(deprecated as opaque monolith, not as guided orchestrator).

Code

docs/architecture.md[50]

+- Interactive install entry point: `admin install` is the guided orchestrator over existing `mint` / `github` / `inference` / `repos` phases, driven by a shared decision tree for humans and agent skills — not a monolithic provisioner ([ADR 0066](ADRs/0066-interactive-admin-install-guide.md)).

Relevance

⭐⭐⭐ High
Team often reconciles doc drift; PR 2698 updated docs to avoid conflicting admin-install guidance.
PR-#2698
PR-#2334

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR adds an architecture bullet stating admin install is the guided orchestrator, but existing
install docs still tell users that fullsend admin install / admin install is deprecated and
recommend using standalone commands instead, without the ADR 0066 clarification. This inconsistency
is new/heightened because the architecture doc is intended to be the "current truth" and will be
read as authoritative guidance.

docs/architecture.md[38-51]
docs/guides/infrastructure/advanced-setup.md[188-190]
docs/guides/dev/cli-internals.md[99-102]
docs/ADRs/0066-interactive-admin-install-guide.md[99-104]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/architecture.md` now asserts that `admin install` is the guided interactive entry point, but other documentation still describes `fullsend admin install` / `admin install` as deprecated in a way that reads like it should not be used at all. This creates conflicting guidance across docs.

## Issue Context
ADR 0066 reframes the deprecation: the old *monolithic provisioner* behavior is deprecated, while `admin install` is intended to exist as a guided orchestrator over standalone phases. The docs that mention deprecation should be updated to reflect that nuance and link to ADR 0066.

## Fix Focus Areas
- docs/guides/infrastructure/advanced-setup.md[188-190]
- docs/guides/dev/cli-internals.md[101-102]
- docs/architecture.md[47-51]

## Suggested changes
- Update the “Deprecated” callouts to explicitly say the *all-in-one/monolithic provisioner* mode is deprecated, not the `admin install` entry point concept.
- Add a short cross-reference to ADR 0066 in those sections.
- If the guided orchestrator is not yet implemented, add a clarifying sentence indicating this is the accepted direction and follow-on implementation work, so readers don’t assume the interactive flow already exists.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ADR 0066 multiple decisions 📜 Skill insight ⚙ Maintainability

Description

The ## Decision section contains six distinct decisions (interactive behavior, command flags,
published YAML tree, coverage requirements, agent skill behavior, and normative-spec deferral). This
violates the requirement that each ADR record exactly one decision, making future change tracking
and supersession ambiguous.

Code

docs/ADRs/0066-interactive-admin-install-guide.md[R60-95]

+1. **Revive `admin install` as a guide, not a monolith.** The command
+   orchestrates installation; it does not re-inline GCP provisioning, mint
+   deploy, or GitHub layer logic. Each step invokes the existing standalone
+   commands (or their library equivalents) with composed flags.
+
+2. **Interactive by default on a TTY.** When stdin is a terminal and required
+   flags are absent, `admin install` runs a guided flow. Non-interactive use
+   keeps today's explicit flags (`--mint-url`, `--inference-project`, etc.).
+   Add `--guided` (force interactive) and `--plan` (print the composed command
+   sequence without executing).
+
+3. **Published decision tree.** Maintain a versioned install decision tree
+   (YAML) in-repo describing questions, branches, prerequisites, and the
+   subcommand(s) each leaf executes. The CLI loads it; changes to install
+   matrix update the tree, not scattered help text.
+
+4. **Coverage.** The tree must reach at least:
+   - single-repo + hosted mint + shared inference (zero-GCP GitHub path);
+   - self-hosted or private mint ([ADR 0059](0059-public-mint-mode-with-wildcard-allowlists.md)
+     tight vs public);
+   - multiple GCP projects / inference accounts;
+   - bulk per-repo rollout via `repos` ([ADR 0057](0057-repos-management.md));
+   - optional `--vendor` ([ADR 0047](0047-vendored-installs-with-vendor-flag.md)).
+   Per-org mode remains a deprecated branch per [ADR 0044](0044-deprecate-per-org-installation-mode.md),
+   shown only when explicitly chosen, with migration guidance.
+
+5. **Agent skills on the same tree.** Provide an install-guidance skill that
+   loads the decision tree and accepts optional context (org size, existing
+   mint URL, compliance constraints, repos in scope). Agents traverse the tree,
+   explain trade-offs, and emit the same `--plan` output humans would get —
+   without bypassing authorization or inventing flags outside the tree.
+
+6. **Normative spec deferred.** The tree schema and leaf command templates are
+   documented alongside the artifact; a `docs/normative/` contract is out of
+   scope until a second consumer (e.g. web installer) needs byte-level
+   interoperability ([ADR 0015](0015-normative-specifications-directory.md)).

Relevance

⭐ Low
Repo ADRs routinely use multi-item “## Decision” lists (e.g., ADR 0059) and accept them.
PR-#1580

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062089 requires each ADR to record exactly one decision. In ADR 0066, the `##
Decision section is a numbered list of six separate decisions (items 1 through 6`), indicating
multiple decisions are being made in a single ADR.

docs/ADRs/0066-interactive-admin-install-guide.md[58-96]
Skill: writing-adrs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/ADRs/0066-interactive-admin-install-guide.md` records multiple distinct decisions in its `## Decision` section (items 1-6). The ADR must be narrowed to exactly one decision, with other decisions moved to separate ADRs or rephrased as consequences/implementation notes.

## Issue Context
Compliance requires one decision per ADR so acceptance/supersession is unambiguous.

## Fix Focus Areas
- docs/ADRs/0066-interactive-admin-install-guide.md[58-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

codecov · 2026-07-05T10:55:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Clarify that the monolithic all-in-one admin install path is deprecated, not the future guided orchestrator described in ADR 0066. Update advanced-setup and cli-internals to cross-reference the ADR and note the interactive wizard is follow-on work. Signed-off-by: Barak Korren <bkorren@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>

fullsend-ai-review · 2026-07-05T11:03:41Z

🤖 Finished Review · ✅ Success · Started 11:03 AM UTC · Completed 11:16 AM UTC
Commit: 8da72c5 · View workflow run →

fullsend-ai-review · 2026-07-05T11:16:47Z

Review

Findings

Low

[missing-context-reference] docs/ADRs/0044-deprecate-per-org-installation-mode.md — ADR 0044 deprecates per-org mode and mentions admin install <org> removal, while new ADR 0066 revives admin install as a guided orchestrator. A cross-reference annotation from ADR 0044 to ADR 0066 would clarify the distinction, though the two ADRs are compatible (0044 deprecates per-org mode, 0066 reframes the command). ADR 0066 already references ADR 0044 in its Decision section.
Remediation: Add a minor annotation to ADR 0044 cross-referencing ADR 0066.
[architectural-coherence] docs/ADRs/0066-interactive-admin-install-guide.md — ADR 0066 references ADR 0044 in the Decision section body text ("Per-org mode remains a deprecated branch per ADR 0044") but does not include it in relates_to frontmatter. Note: relates_to uses topic labels (e.g., agent-infrastructure), not ADR references, so adding an ADR number would be inconsistent with the schema convention. The body cross-reference is sufficient.
[outdated-deprecation-guidance] docs/guides/getting-started/org-mode.md:6 — The deprecation notice references only ADR 0044 without mentioning ADR 0066's accepted direction for reviving admin install as a guided orchestrator. Users reading this page may not realize the command itself is not deprecated — only per-org mode is.
Remediation: Update the deprecation notice to distinguish between deprecated per-org mode (ADR 0044) and the accepted interactive orchestrator direction (ADR 0066).
[potentially-stale-reference] docs/plans/deprecate-per-org-install.md:88 — The deprecation plan directs users to fullsend admin install <owner/repo>, which remains correct guidance. No update needed until the ADR 0066 orchestrator implementation begins.

Previous run

Review

Findings

Low

[architectural-coherence] docs/ADRs/0066-interactive-admin-install-guide.md — ADR 0066 proposes reviving admin install as an interactive guided orchestrator, but does not explicitly cross-reference ADR 0044 (which deprecates per-org installation mode) to clarify the relationship. The ADR's Context section acknowledges the deprecation of the monolithic path, and the updated docs in this PR correctly distinguish between deprecated monolithic mode and the accepted guided entry point. However, adding a direct cross-reference to ADR 0044 in the Status or Context section would make the relationship between the two decisions more discoverable.
Remediation: Consider adding ADR 0044 to the relates_to frontmatter or adding a brief note in the Context section clarifying that ADR 0044 deprecates per-org mode (not the admin install command itself), and this ADR reframes the command as a guided orchestrator over per-repo standalone phases.

Labels: PR adds a new ADR about the install entry point and updates installation documentation

Resolve docs/architecture.md conflict by keeping both ADR 0066 (interactive admin install guide) and ADR 0067 (GitLab cron polling dispatch). Signed-off-by: Barak Korren <bkorren@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>

fullsend-ai-review · 2026-07-07T07:32:22Z

🤖 Review · ❌ Terminated · Started 7:32 AM UTC · Ended 7:49 AM UTC
Commit: e8381e3 · View workflow run →

ifireball · 2026-07-07T07:36:52Z

Addressed the Qodo docs-conflict finding in 8da72c5 (reconcile monolithic deprecation vs ADR 0066 guided orchestrator in advanced-setup.md and cli-internals.md) and rebased onto current main in 59b0509f (resolved docs/architecture.md merge conflict — kept both ADR 0066 and ADR 0067 bullets). CI is green on the latest commit.

fullsend-ai-review · 2026-07-07T07:49:29Z

🤖 Finished Review · ✅ Success · Started 7:32 AM UTC · Completed 7:49 AM UTC
Commit: 59b0509 · View workflow run →

rh-hemartin · 2026-07-08T11:36:21Z

+## Context
+
+Fullsend installation spans mint trust, inference WIF, GitHub Apps, scaffold
+delivery, and per-repo vs per-org scope. Standalone commands (`mint`,


Per-org is deprecated, not worth adding it here in my opinion.

rh-hemartin · 2026-07-08T11:40:41Z

+That split reduced coupling but increased cognitive load: adopters must
+understand which role runs which phase, whether to use the hosted mint or a
+private one, how many GCP projects are involved, and whether
+[ADR 0047](0047-vendored-installs-with-vendor-flag.md) vendoring applies — from
+a single repo on hosted services through a multi-org footprint with private
+mints and several inference accounts. Agents assisting onboarding face the same
+matrix without a single machine-readable decision model.


I dont think this is true. The decoupling removed cognitive load. Users know fullsend mint is to be run by the admin team, so they don't need to understand it. So they don't need to understand if they need a hosted mint or a private one. Vendoring is not even exposed to them in the getting started guide. They do know a single GCP is involved (see the getting inference guide). And nowhere in the getting started roles are mentioned, so they don't need to understand them right away.

They can defer acquiring the knowledge, they are not even expose to much of this knowledge up front. That is reserved for "next steps".

So I would say this premise is false

rh-hemartin · 2026-07-08T11:41:45Z

+### Option C: New top-level `fullsend install`
+
+Same behavior as B but a new command. Rejected — `admin install` is already the
+familiar entry point and matches org-admin mental models.


I would go with this, if we aim to simplify, we should surface this to top level so it is easier.

rh-hemartin · 2026-07-08T11:43:32Z

+## Decision
+
+1. **Revive `admin install` as a guide, not a monolith.** The command
+   orchestrates installation; it does not re-inline GCP provisioning, mint


"it does not re-inline GCP provisioning, ming dpeloy or GitHub layer logic" seems contradictory with the next point, where it says that non-interactive usage keeps today's explicit flags. I would just keep it as an interactive way of installing.

rh-hemartin · 2026-07-08T11:45:41Z

+3. **Published decision tree.** Maintain a versioned install decision tree
+   (YAML) in-repo describing questions, branches, prerequisites, and the
+   subcommand(s) each leaf executes. The CLI loads it; changes to install
+   matrix update the tree, not scattered help text.


Could you add an example of the decision tree? I don't see the difference between storing a decision tree and just storing the answers.

rh-hemartin · 2026-07-08T11:47:31Z

+- User-facing docs that deprecated all-in-one `admin install` should be
+  annotated: deprecated as an opaque monolith, not as the guided entry point.


I don't see value in annotating them, just remove them and add the new ones in place. The docs would talk about the command being an interactive experience.

rh-hemartin · 2026-07-08T11:50:10Z

+- The decision tree becomes a maintained product artifact; install changes
+  require tree updates and tests.
+- Agents gain a bounded, testable install guide instead of improvising from
+  prose docs.


Could you expand a bit on the testability?

ifireball requested a review from a team as a code owner July 5, 2026 10:51

github-actions Bot deployed to site-preview July 5, 2026 10:53 View deployment

qodo-code-review Bot reviewed Jul 5, 2026

View reviewed changes

Comment thread docs/architecture.md

github-actions Bot deployed to site-preview July 5, 2026 11:04 View deployment

This comment was marked as outdated.

Sign in to view

fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge component/docs User-facing documentation component/install CLI install and app setup labels Jul 5, 2026

merge: reconcile with upstream main

59b0509

Resolve docs/architecture.md conflict by keeping both ADR 0066 (interactive admin install guide) and ADR 0067 (GitLab cron polling dispatch). Signed-off-by: Barak Korren <bkorren@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot deployed to site-preview July 7, 2026 07:33 View deployment

fullsend-ai-review Bot approved these changes Jul 7, 2026

View reviewed changes

fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge and removed ready-for-merge All reviewers approved — ready to merge labels Jul 7, 2026

ifireball self-assigned this Jul 7, 2026

rh-hemartin reviewed Jul 8, 2026

View reviewed changes

		- User-facing docs that deprecated all-in-one `admin install` should be
		annotated: deprecated as an opaque monolith, not as the guided entry point.

Uh oh!

Conversation

ifireball commented Jul 5, 2026

Summary

Context

Test plan

Uh oh!

fullsend-ai-review Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qodo-code-review Bot commented Jul 5, 2026

PR Summary by Qodo

Uh oh!

github-actions Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Site preview

Uh oh!

qodo-code-review Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

codecov Bot commented Jul 5, 2026

Codecov Report

Uh oh!

fullsend-ai-review Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review

Findings

Low

Review

Findings

Low

Uh oh!

This comment was marked as outdated.

Uh oh!

fullsend-ai-review Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ifireball commented Jul 7, 2026

Uh oh!

fullsend-ai-review Bot commented Jul 7, 2026

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

rh-hemartin Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fullsend-ai-review Bot commented Jul 5, 2026 •

edited

Loading

github-actions Bot commented Jul 5, 2026 •

edited

Loading

qodo-code-review Bot commented Jul 5, 2026 •

edited

Loading

fullsend-ai-review Bot commented Jul 5, 2026 •

edited

Loading

fullsend-ai-review Bot commented Jul 5, 2026 •

edited

Loading

fullsend-ai-review Bot commented Jul 7, 2026 •

edited

Loading